<html>
<head><meta charset="utf-8"><title>semver and Cargo feature flags · general · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/index.html">general</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html">semver and Cargo feature flags</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="161581499"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161581499" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161581499">(Mar 24 2019 at 14:23)</a>:</h4>
<p>If I have a function that is <em>only</em> exposed when a Cargo feature is enabled and I change the API of that function, what version number bump would you do?</p>



<a name="161581501"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161581501" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161581501">(Mar 24 2019 at 14:23)</a>:</h4>
<p>/poll</p>



<a name="161586277"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161586277" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Leo Le Bouter <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161586277">(Mar 24 2019 at 16:34)</a>:</h4>
<p><span class="user-mention" data-user-id="116155">@Jake Goulding</span>  Any API change should be major, should it not? I'd delay the API change in another major release along with lots of other API changes to make it meaningful, but I don't think you should break API compatibility just like that.</p>



<a name="161618486"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161618486" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> DevQps <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161618486">(Mar 25 2019 at 06:39)</a>:</h4>
<p>It feels a bit painful to increment the major version number for such (smaller) things but I guess major still would be the best. After all: Code could break when upgrading</p>



<a name="161639521"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161639521" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Luca Barbato <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161639521">(Mar 25 2019 at 12:52)</a>:</h4>
<p>You could feature-gate the new API with a new feature and bump minor as yet another alternative.</p>



<a name="161665362"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161665362" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161665362">(Mar 25 2019 at 17:15)</a>:</h4>
<p>That leads nicely to my actual but related question...</p>
<p>If I have a function that is only exposed when a Cargo feature is enabled, <em>I've specifically stated that that feature flag is for unstable features</em>, and I change the API of that function, what version number bump would you do?</p>



<a name="161665405"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161665405" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161665405">(Mar 25 2019 at 17:16)</a>:</h4>
<p>/poll</p>



<a name="161833251"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161833251" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> DevQps <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161833251">(Mar 27 2019 at 06:34)</a>:</h4>
<p>Mmm, good questions :). My first gut feeling says that a minor increment is appropriate here. Since the main stable API doesn't change.</p>
<p>But at a second thought I believe a different approach might be better. It's just a suggestion but I think I would dp it like this:</p>
<p>Semver states thst you can do whatever you want when at the 0 major version. So in case you feel like your project in general hasn't reached a stable API I would just increment the minor number.</p>
<p>If your project has however reached at least major 1, I think the best way to tackle this is to only publish new stable features of crates. On publishing new (backwards compatible) changes, even if its in a feature, you change the minor, and for non-backwards compatible changes you'd change major (even for features)</p>
<p>When a feature contains unstable functionality and you've already reached a major version, I would allow users to use/test it via a direct repository tag/branch:</p>
<p><code>project = { git = "https://github.com/userhere/myproj", tag = "1.32.5-beta" }</code></p>
<p>Or something like this. If you'd specify this in the README people would still have access to unstable features whereas they can rely upon a stable API when using <a href="http://crates.io" target="_blank" title="http://crates.io">crates.io</a>. When the unstable features are merged they would be published as well!</p>
<p>A bit of a long story, but it's just a though :)</p>



<a name="161851980"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161851980" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161851980">(Mar 27 2019 at 12:00)</a>:</h4>
<blockquote>
<p>Semver states thst you can do whatever you want when at the 0 major version. So in case you feel like your project in general hasn't reached a stable API I would just increment the minor number.</p>
</blockquote>
<p>FWIW, what Cargo implements is a slight twist on this. 0.2 is considered a breaking change to 0.1, and 0.0.2 is a breaking change to 0.0.1. 0.1.0 to 0.1.1 is not expected to be a breaking change.</p>



<a name="161854244"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161854244" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Nemo157 <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161854244">(Mar 27 2019 at 12:33)</a>:</h4>
<p>My thoughts are that unstable features don’t contribute to semver at all</p>



<a name="161854265"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161854265" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Nemo157 <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161854265">(Mar 27 2019 at 12:33)</a>:</h4>
<p>If you were able to release the changes to the same version that would be fine</p>



<a name="161854325"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/semver%20and%20Cargo%20feature%20flags/near/161854325" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Nemo157 <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/semver.20and.20Cargo.20feature.20flags.html#161854325">(Mar 27 2019 at 12:34)</a>:</h4>
<p>But since you can’t doing a patch update to be able to release a new version is all that’s needed</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>